home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dtrsna.z / dtrsna
Encoding:
Text File  |  2002-10-03  |  9.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))                                                          DDDDTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DTRSNA - estimate reciprocal condition numbers for specified eigenvalues
  10.      and/or right eigenvectors of a real upper quasi-triangular matrix T (or
  11.      of any matrix Q*T*Q**T with Q orthogonal)
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      SUBROUTINE DTRSNA( JOB, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, S,
  15.                         SEP, MM, M, WORK, LDWORK, IWORK, INFO )
  16.  
  17.          CHARACTER      HOWMNY, JOB
  18.  
  19.          INTEGER        INFO, LDT, LDVL, LDVR, LDWORK, M, MM, N
  20.  
  21.          LOGICAL        SELECT( * )
  22.  
  23.          INTEGER        IWORK( * )
  24.  
  25.          DOUBLE         PRECISION S( * ), SEP( * ), T( LDT, * ), VL( LDVL, *
  26.                         ), VR( LDVR, * ), WORK( LDWORK, * )
  27.  
  28. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  29.      These routines are part of the SCSL Scientific Library and can be loaded
  30.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  31.      directs the linker to use the multi-processor version of the library.
  32.  
  33.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  34.      4 bytes (32 bits). Another version of SCSL is available in which integers
  35.      are 8 bytes (64 bits).  This version allows the user access to larger
  36.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  37.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  38.      only one of the two versions; 4-byte integer and 8-byte integer library
  39.      calls cannot be mixed.
  40.  
  41. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  42.      DTRSNA estimates reciprocal condition numbers for specified eigenvalues
  43.      and/or right eigenvectors of a real upper quasi-triangular matrix T (or
  44.      of any matrix Q*T*Q**T with Q orthogonal). T must be in Schur canonical
  45.      form (as returned by DHSEQR), that is, block upper triangular with 1-by-1
  46.      and 2-by-2 diagonal blocks; each 2-by-2 diagonal block has its diagonal
  47.      elements equal and its off-diagonal elements of opposite sign.
  48.  
  49.  
  50. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  51.      JOB     (input) CHARACTER*1
  52.              Specifies whether condition numbers are required for eigenvalues
  53.              (S) or eigenvectors (SEP):
  54.              = 'E': for eigenvalues only (S);
  55.              = 'V': for eigenvectors only (SEP);
  56.              = 'B': for both eigenvalues and eigenvectors (S and SEP).
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))                                                          DDDDTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      HOWMNY  (input) CHARACTER*1
  75.              = 'A': compute condition numbers for all eigenpairs;
  76.              = 'S': compute condition numbers for selected eigenpairs
  77.              specified by the array SELECT.
  78.  
  79.      SELECT  (input) LOGICAL array, dimension (N)
  80.              If HOWMNY = 'S', SELECT specifies the eigenpairs for which
  81.              condition numbers are required. To select condition numbers for
  82.              the eigenpair corresponding to a real eigenvalue w(j), SELECT(j)
  83.              must be set to .TRUE.. To select condition numbers corresponding
  84.              to a complex conjugate pair of eigenvalues w(j) and w(j+1),
  85.              either SELECT(j) or SELECT(j+1) or both, must be set to .TRUE..
  86.              If HOWMNY = 'A', SELECT is not referenced.
  87.  
  88.      N       (input) INTEGER
  89.              The order of the matrix T. N >= 0.
  90.  
  91.      T       (input) DOUBLE PRECISION array, dimension (LDT,N)
  92.              The upper quasi-triangular matrix T, in Schur canonical form.
  93.  
  94.      LDT     (input) INTEGER
  95.              The leading dimension of the array T. LDT >= max(1,N).
  96.  
  97.      VL      (input) DOUBLE PRECISION array, dimension (LDVL,M)
  98.              If JOB = 'E' or 'B', VL must contain left eigenvectors of T (or
  99.              of any Q*T*Q**T with Q orthogonal), corresponding to the
  100.              eigenpairs specified by HOWMNY and SELECT. The eigenvectors must
  101.              be stored in consecutive columns of VL, as returned by DHSEIN or
  102.              DTREVC.  If JOB = 'V', VL is not referenced.
  103.  
  104.      LDVL    (input) INTEGER
  105.              The leading dimension of the array VL.  LDVL >= 1; and if JOB =
  106.              'E' or 'B', LDVL >= N.
  107.  
  108.      VR      (input) DOUBLE PRECISION array, dimension (LDVR,M)
  109.              If JOB = 'E' or 'B', VR must contain right eigenvectors of T (or
  110.              of any Q*T*Q**T with Q orthogonal), corresponding to the
  111.              eigenpairs specified by HOWMNY and SELECT. The eigenvectors must
  112.              be stored in consecutive columns of VR, as returned by DHSEIN or
  113.              DTREVC.  If JOB = 'V', VR is not referenced.
  114.  
  115.      LDVR    (input) INTEGER
  116.              The leading dimension of the array VR.  LDVR >= 1; and if JOB =
  117.              'E' or 'B', LDVR >= N.
  118.  
  119.      S       (output) DOUBLE PRECISION array, dimension (MM)
  120.              If JOB = 'E' or 'B', the reciprocal condition numbers of the
  121.              selected eigenvalues, stored in consecutive elements of the
  122.              array. For a complex conjugate pair of eigenvalues two
  123.              consecutive elements of S are set to the same value. Thus S(j),
  124.              SEP(j), and the j-th columns of VL and VR all correspond to the
  125.              same eigenpair (but not in general the j-th eigenpair, unless all
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))                                                          DDDDTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))
  137.  
  138.  
  139.  
  140.              eigenpairs are selected).  If JOB = 'V', S is not referenced.
  141.  
  142.      SEP     (output) DOUBLE PRECISION array, dimension (MM)
  143.              If JOB = 'V' or 'B', the estimated reciprocal condition numbers
  144.              of the selected eigenvectors, stored in consecutive elements of
  145.              the array. For a complex eigenvector two consecutive elements of
  146.              SEP are set to the same value. If the eigenvalues cannot be
  147.              reordered to compute SEP(j), SEP(j) is set to 0; this can only
  148.              occur when the true value would be very small anyway.  If JOB =
  149.              'E', SEP is not referenced.
  150.  
  151.      MM      (input) INTEGER
  152.              The number of elements in the arrays S (if JOB = 'E' or 'B')
  153.              and/or SEP (if JOB = 'V' or 'B'). MM >= M.
  154.  
  155.      M       (output) INTEGER
  156.              The number of elements of the arrays S and/or SEP actually used
  157.              to store the estimated condition numbers.  If HOWMNY = 'A', M is
  158.              set to N.
  159.  
  160.      WORK    (workspace) DOUBLE PRECISION array, dimension (LDWORK,N+1)
  161.              If JOB = 'E', WORK is not referenced.
  162.  
  163.      LDWORK  (input) INTEGER
  164.              The leading dimension of the array WORK.  LDWORK >= 1; and if JOB
  165.              = 'V' or 'B', LDWORK >= N.
  166.  
  167.      IWORK   (workspace) INTEGER array, dimension (N)
  168.              If JOB = 'E', IWORK is not referenced.
  169.  
  170.      INFO    (output) INTEGER
  171.              = 0: successful exit
  172.              < 0: if INFO = -i, the i-th argument had an illegal value
  173.  
  174. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  175.      The reciprocal of the condition number of an eigenvalue lambda is defined
  176.      as
  177.  
  178.              S(lambda) = |v'*u| / (norm(u)*norm(v))
  179.  
  180.      where u and v are the right and left eigenvectors of T corresponding to
  181.      lambda; v' denotes the conjugate-transpose of v, and norm(u) denotes the
  182.      Euclidean norm. These reciprocal condition numbers always lie between
  183.      zero (very badly conditioned) and one (very well conditioned). If n = 1,
  184.      S(lambda) is defined to be 1.
  185.  
  186.      An approximate error bound for a computed eigenvalue W(i) is given by
  187.  
  188.                          EPS * norm(T) / S(i)
  189.  
  190.      where EPS is the machine precision.
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))                                                          DDDDTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      The reciprocal of the condition number of the right eigenvector u
  207.      corresponding to lambda is defined as follows. Suppose
  208.  
  209.                  T = ( lambda  c  )
  210.                      (   0    T22 )
  211.  
  212.      Then the reciprocal condition number is
  213.  
  214.              SEP( lambda, T22 ) = sigma-min( T22 - lambda*I )
  215.  
  216.      where sigma-min denotes the smallest singular value. We approximate the
  217.      smallest singular value by the reciprocal of an estimate of the one-norm
  218.      of the inverse of T22 - lambda*I. If n = 1, SEP(1) is defined to be
  219.      abs(T(1,1)).
  220.  
  221.      An approximate error bound for a computed right eigenvector VR(i) is
  222.      given by
  223.  
  224.                          EPS * norm(T) / SEP(i)
  225.  
  226.  
  227. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  228.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  229.  
  230.      This man page is available only online.
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.